<html>
<body>

Provides the interface to the Project Darkstar Server. <p>

<h3>Implementation-specific information</h3>

<h4>Configuration properties</h4>

See <a href="com/sun/sgs/app/doc-files/config-properties.html">this
document</a> for a list of configuration properties supported by the
current implementation of the Project Darkstar Server.

<h4>Modifications and updates to managed objects</h4>

You can using logging to obtain information about instances of {@link
com.sun.sgs.app.ManagedObject} that were modified without being marked
for update.  Developers can use this information to help determine if
they can safely disable the automatic detection of object modifications
&mdash; see the documentation for the <a
href="com/sun/sgs/app/doc-files/config-properties.html#com.sun.sgs.impl.service.data.DataServiceImpl.detect.modifications"
>com.sun.sgs.impl.service.data.DataServiceImpl.detect.modifications</a>
property. <p>

Information about managed objects that were modified and not marked for
update is logged to the {@link java.util.logging.Logger Logger} named
{@code com.sun.sgs.impl.service.data.DataServiceImpl.detect.modifications} at
level {@link java.util.logging.Level#FINEST FINEST}.  This logging is
only performed if detection of modifications is enabled.

<h3>API conventions</h3>

Interfaces in this API do not extend {@link java.io.Serializable} even
if classes that implement those interfaces are required to implement
it. <p>

The API uses this approach to avoid an issue involving
the <code>serialVersionUID</code> field.  To guard
against <code>serialVersionUID</code> mismatches, as well as to improve
performance, any class or interface that
extends <code>Serializable</code> should declare a
<code>serialVersionUID</code> field.  Since public interfaces can only
declare public members, a public interface that
extends <code>Serializable</code> would need to have a
public <code>serialVersionUID</code> field, meaning that any classes
implementing the interface would inherit
its <code>serialVersionUID</code>, and so would be prevented from
controlling their versioning separately.  This issue does not crop up
for interfaces that do not extend Serializable, since they by
definition have a <code>serialVersionUID</code> of <code>0</code>.

<h3>Documentation conventions</h3>

Unless explicitly specified otherwise, all documentation for these APIs
uses the following conventions:

<ul>
<li> If <code>null</code> is not explicitly specified as an acceptable
     value for a method parameter, then the method does not
     permit <code>null</code> to be passed as a value for that
     parameter, and will throw a {@link java.lang.NullPointerException}
     if <code>null</code> is passed (though it is left unspecified
     whether or not <code>NullPointerException</code> takes precedence
     over other types of exceptions that could also be thrown).

<li> If <code>null</code> is not explicitly specified as an acceptable
     value for a method to return, then the method is not permitted to
     return <code>null</code>.

<li> If <code>null</code> is not explicitly specified as an acceptable
     value for a given collection (e.g. {@link java.util.Collection},
     {@link java.util.List}, or {@link java.util.Set}) to contain, then
     the collection is not permitted to contain <code>null</code>
     elements.
</ul>

Methods that can accept or return <code>null</code> values generally
specify this at least in their parameter-level (i.e. <code>@param</code>
tag) or return value-level (i.e. <code>@return</code> tag)
documentation.

</body>
</html>
